<HTML>
<HEAD>
<META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=windows-
1252">
<META NAME="Generator" CONTENT="Microsoft Word 97">
<TITLE>Ports Class Installer
</TITLE>
</HEAD>
<BODY LINK="#0000ff">

<FONT FACE="Verdana" SIZE=5><H2>Ports Class Installer
</H2>
</FONT><FONT FACE="Verdana" SIZE=2>

<H3>SUMMARY</H3></FONT><FONT FACE="Verdana" SIZE=2>
<P>
This sample demonstrates a class installer and property page provider for the
ports class of devices.   The ports class is divided into two types of devices,
COM (serial) ports and LPT or ECP (printer) ports.  A separate property page is
provided for each type of device.  Furthermore, the class installer distinguishes
both types of devices and installs each type of device differently.
</P>

<blockquote>
<b>Note:</b> When using this sample, you need to code whatever is specific to your class.  This sample is specific to port class only. Copying and pasting this code without modification may lead to disaster for other classes.
</blockquote>

The sample runs on the x86 platform.  It has only been tested in a 32-bit environment. 

<p>
<H3>BUILDING THE SAMPLE</H3></FONT><FONT FACE="Verdana" 
SIZE=2><P>

Enter the checked or free build environment.  Then, 
while in the Class Installer sample directory, type <b>build</b>.  A successful build produces 
the executable <i>pnpports.dll.</i>

<H3>RELEASE NOTES</H3></FONT><FONT FACE="Verdana" SIZE=2><P>

<H3>CODE TOUR</H3>
<H4>File Manifest</H4>
</FONT>
<U><PRE>File&#9;&#9;Description</U>
<I>advandlg.c</I>&#9;Advanced dialog for COM port property page
<I>ports.h</I>&#9;    Ports header file
<I>ports.c</I>&#9;    Class Installer for the Ports clas
<I>pp.c</I>&#9;    Property Page Provider for COM ports
<I>pp.h</I>&#9;    Definitions for pp.c
<I>pp_lpt.c</I>&#9;Property Page Provider for LPT and ECP ports
<I>pp_lpt.h</I>&#9;Definitions for pp_lpt.c
<I>util.c</I>&#9;    Utility functions
<I>ports.rc</I>&#9;Resources
<I>ports.rc2</I>&#9;Resources
<I>pnpports.def</I>&#9;Exports file
<I>ports.htm</I>&#9;This file
<I>Sources</I>&#9;    needed to build
<I>Makefile</I>&#9;needed to build
</pre>

<h4><font face="Verdana">Programming Tour</font></h4>
<font face="Verdana" size="2">

<p>This programming tour shows the specifics of the class installer and how the property
pages are added and initialized.</p>

<h5><font face="Verdana">The Class Installer</font></h5>

<p>When the device is being installed, the class installer must first determine whether a COM or LPT port is being installed.  The class installer 
relies on the .inf file that installed the device to write this value into the
registry.   The .inf must include an AddReg directive which writes a binary value
named <b>PortSubClass</b> in the driver key for the device instance.  Please see
the sections [LptPort.AddReg], [EcpPort.AddReg], and [ComPort.AddReg] in
<I>msports.inf</I>.</p>

<p>The class installer handles ths following DIF codes:</p>

<font FACE="Verdana" SIZE="2">
<ul>
 <li>DIF_INSTALLDEVICE</li>
 <li>DIF_REMOVE</li>
</ul>
</font>

<p>The handling DIF_INSTALLDEVICE is specific to the device type.   This example
demonstrates how to handle DIF_INSTALLDEVICE for COM ports.  While the Ports 
Class installer shipped with the system also handles LPT ports in
DIF_INSTALLDEVICE, this sample just informs Setup to perform the default
installation.</p>

<p>The primary purpose of the COM ports class installer is to assign a port name,
e.g. COM1, to the device and to create a friendly name for the device that
includes the port name.  Providing a unique name to the port can prove to be 
difficult; with that in mind, a COM name database was created.   The API for the
database resides in <I>msports.dll</I> (which <I>pnpports.dll</I> links against).  The
database provides concurrent access to the list of names that have already
been claimed by other ports and modems.</p>

<p>The COM port class installer assigns a name to the port in this priority:

<font FACE="Verdana" SIZE="2">
<ol>
 <li>The presence of a value named <B>PortName</B> in the device node.  This value will
 have been written to the device node by either the class installer (if this is
 an upgrade) or by the mapper, a kernel component that creates devices based on
 what the BIOS reports.</li>
 <li>The presence of a value named <B>DosDeviceName</B> in the device node.  This 
 value will have been written to the device node by the ACPI driver.</li>
 <li>If the enumerator is ACPI or root (and the root enumerated flag is not
 set), then the first free port name, starting at COM1, is chosen.</li>
 <li>The COM name database is consulted and the next free port name is assigned
 to the device.</li>
</ol>
</font>

</p>

<p>The friendly name for the device must now be set.  This is done by
concatenating the device description of the device with port name chosen for 
the device.  For instance, if the device description is "Communications Port"
and the chosen port name is COM2, then the friendly name would be
"Communications Port (COM2)."</p>

<p>If the DIF code is DIF_REMOVE and the device is a COM port, the port name is freed from the
COM name database.</p>

<h5><font face="Verdana">Property Pages</font></h5>

<p>The property pages are loaded using the <B>EnumPropPages32</B> value in the device driver key of the registry. Please see the sections 
[LptPort.NT.AddReg] and [ComPort.NT.AddReg] in <I>msports.inf</I> to see how to
correctly write the values via an .inf file.</p>

<p>When the property page provider function is called
(<B>SerialPortPropPageProvider</B> or <B>ParallelPortPropPageProvider</B>), it sets the
<I>pfnCallback</I> field of the <B>PROPSHEETPAGE</B>structure.  This is done so that the  
<B>PPORT_PARAMS</B> or <B>PLPT_PORT_PARAMS</B> structure that was previously allocated will be freed whether the page was created or not.  Note that the property page is not created until 
the user chooses it for the first time.
</p>

</font>
<P ALIGN="CENTER"><A HREF="#top"><FONT FACE="Verdana" SIZE=2>
Top of page</FONT></A><FONT FACE="Verdana" SIZE=2> </P></FONT>

<TABLE CELLSPACING=0 BORDER=0 WIDTH=624>
 <TR>
  <TD VALIGN="MIDDLE" BGCOLOR="#00ffff" HEIGHT=2><P></TD>
 </TR>
</TABLE>

<FONT FACE="Microsoft Sans Serif" SIZE=1>
<P> &copy; 2005 Microsoft Corporation</FONT>
<FONT FACE="Verdana" SIZE=2> </P></FONT>

</BODY>


